Release notes

2023r3

Introduction of copyright api

From this version, the copyright API has been introduced. It allows to create, update and delete copyright sheets, copyright materials and material uses. It can also be used to link copyright sheets to content.

The full API definition can be consulted in the API explorer.

In a high-level overview, the API contains the following calls.

Copyright sheets

POST /copyrightSheets

The version and status attributes are mandatory. The available values can be retrieved using the GET /copyrightVersions and GET /copyrightVersions/{versionId}/statuses calls.

It is possible to define a list of material uses with the materialUseList attribute. The materials already have to exist. For each material use in the array, the materialId and durationInUse are mandatory. When this materialUseList attribute is specified, all existing material uses will be replaced by the list specified in the call.

By specifying the contentId, it is possible to link a copyright sheet to content. If this is not provided, the created copyright sheet will be present in the copyright import assistant.

PUT /copyrightSheets/{copyrightSheetId}

The copyrightSheetId attribute is mandatory.

For the materialUseList, the same conditions apply as in the POST call.

DELETE /copyrightSheets/{copyrightSheetId}

GET /copyrightSheet/{copyrightSheetId}

When a user is logged in and authenticated, the permission needed for these calls is Copyright Management (browser for the GET call and editor).

Copyright materials

POST, PUT /simpleMaterials
POST, PUT /musicMaterials
POST, PUT /textMaterials
POST, PUT /artMaterials
POST, PUT /filmMaterials
POST, PUT /photoMaterials
POST, PUT /otherMaterials
DELETE /materials
GET /materials

When a user is logged in and authenticated, the permission needed for these calls is Material Management (browser for the GET call and editor).

POST calls

No mandatory fields. When created, the type of the material will automatically be the same as that of the call.

For example, if you use the POST /musicMaterial call, you will automatically create a music material.

If the materialId is provided in the call and matches the external reference of an existing copyright material of the same type as the call, this material will be updated. If a material exists with that same reference but with a different type, an error is returned.

PUT calls

The materialId is mandatory and should belong to a material with the same type as the call. If not, an error is returned.

Material uses

It is already possible to create material uses with the copyright sheet calls but the materialUseList attribute in those calls always replaces all existing material uses. To manage individual material uses, the following calls can be used.

POST /materialUses

The following attributes are mandatory:

copyrightId: the external reference of the copyright sheet on which the use should be created
materialId: the external reference of the material that will be used
durationInUse: the duration of the material use on the copyright sheet in format HH:MM:SS.

PUT /materialUses/{materialUseId}

The materialUseId attribute is mandatory.

DELETE /materialUses/{materialUseId}

GET /materialUses/{materialUseId}

GET calls for drop-down lists

GET /copyrightVersions

Maps to WOnCopyRightSheetVersion drop-down list

GET /copyrightVersions/{versionId}/statuses

Maps to WOnCopyRightSheetStatus

GET /materialUseSubTypes/{materialType}

Maps to PSIMaterialType

GET /castFunctions

Maps to Function

GET /castTypes

Maps to PSICastType

GET /licences

Maps to PSICastParticipantLicenseType

GET /carriers

Maps to PSIAudioCarrier

GET /soundvalues

Maps to Sound

GET /languages

Maps to PSILanguage

GET /countries

Maps to PSICountry